Skip to content

docs: correct and complete library documentation#337

Open
mvandeberg wants to merge 1 commit into
cppalliance:develop-2from
mvandeberg:docs/pass2
Open

docs: correct and complete library documentation#337
mvandeberg wants to merge 1 commit into
cppalliance:develop-2from
mvandeberg:docs/pass2

Conversation

@mvandeberg

@mvandeberg mvandeberg commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Bring the documentation in line with the implementation across public-header docstrings and the Antora manual.

Headers:

  • read_until: the match position is returned on success, not on error.
  • dynamic_buffer: flat/circular/vector/string are all adapters over external storage; the value-type category is for user-defined owning buffers.
  • Add missing docstrings to public symbols: task/quitter promise types, the delay awaitable, fuse::result, make_buffer overloads, the recycling memory resource, and frame_alloc_mixin's operator new.
  • Remove buffer_param references to a nonexistent max_size member.
  • Note that the recycling memory resource ignores the requested alignment.
  • Fix this_coro/run_async examples and document the environment precondition.
  • Correct the executor concept example, io_runnable handle() constness, the executor_ref example, pull_from parameter descriptions, and timeout/when_all and when_any @throws clauses.
  • Name strand's template parameter Ex and correct its dispatch condition.
  • Correct the overstated no-throw guarantee on the test mock streams.

Manual:

  • Document the real fixed 16-entry buffer window for system I/O.
  • Correct the mock source/sink prose and member tables.
  • async_event is a manual-reset event, not one-shot.
  • Fix the custom-dynamic-buffer read loop to check end-of-stream before commit.
  • Remove a misplaced whole-catalog summary section.
  • Correct the type-erasure vtable taxonomy and the run_async wrapper snippet.
  • Replace the cancellation page's timeout example with the real timeout() combinator; bind executor_ref to a named executor.
  • Document when_all/when_any all-fail semantics; replace the FrameAllocator concept with the real allocator requirements and document frame_alloc_mixin.
  • Document read into a DynamicBuffer, the ReadSource read overload, read_until, and write_now; the composed write takes its buffer sequence by value.
  • Smaller buffer/stream/source corrections (byte-size note, empty/partial read).

Closes #296
Closes #273

@mvandeberg mvandeberg changed the base branch from develop to develop-2 June 24, 2026 15:46
@cppalliance-bot

cppalliance-bot commented Jun 24, 2026

Copy link
Copy Markdown

An automated preview of the documentation is available at https://337.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-06-24 18:43:02 UTC

@cppalliance-bot

cppalliance-bot commented Jun 24, 2026

Copy link
Copy Markdown

GCOVR code coverage report https://337.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://337.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://337.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-06-24 19:04:22 UTC

@codecov

codecov Bot commented Jun 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.15%. Comparing base (9144290) to head (9d233ed).
⚠️ Report is 5 commits behind head on develop-2.

Additional details and impacted files

Impacted file tree graph

@@              Coverage Diff              @@
##           develop-2     #337      +/-   ##
=============================================
+ Coverage      98.07%   98.15%   +0.07%     
=============================================
  Files            164       82      -82     
  Lines           8774     4165    -4609     
=============================================
- Hits            8605     4088    -4517     
+ Misses           169       77      -92     
Flag Coverage Δ
linux 98.15% <ø> (-0.03%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 99 files with indirect coverage changes


Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9144290...9d233ed. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Bring the documentation in line with the implementation across public-header
docstrings and the Antora manual.

Headers:
- read_until: the match position is returned on success, not on error.
- dynamic_buffer: flat/circular/vector/string are all adapters over external
  storage; the value-type category is for user-defined owning buffers.
- Add missing docstrings to public symbols: task/quitter promise types, the
  delay awaitable, fuse::result, make_buffer overloads, the recycling memory
  resource, and frame_alloc_mixin's operator new.
- Remove buffer_param references to a nonexistent max_size member.
- Note that the recycling memory resource ignores the requested alignment.
- Fix this_coro/run_async examples and document the environment precondition.
- Correct the executor concept example, io_runnable handle() constness, the
  executor_ref example, pull_from parameter descriptions, and timeout/when_all
  and when_any @throws clauses.
- Name strand's template parameter Ex and correct its dispatch condition.
- Correct the overstated no-throw guarantee on the test mock streams.

Manual:
- IoAwaitable: the custom-awaitable example resumes the caller by wrapping its
  handle in a continuation and posting that to the executor; dispatch/post take
  a continuation&, not a raw coroutine_handle.
- Construct buffers from arrays/containers with make_buffer, not mutable_buffer
  (which has no array/range constructor), in the read/stream examples; a
  string_view is not itself a ConstBufferSequence and must be wrapped with
  make_buffer.
- Document the real fixed 16-entry buffer window for system I/O.
- Correct the mock source/sink prose and member tables.
- async_event is a manual-reset event, not one-shot.
- Fix the custom-dynamic-buffer read loop to check end-of-stream before commit.
- Remove a misplaced whole-catalog summary section.
- Correct the type-erasure vtable taxonomy and the run_async wrapper snippet.
- Replace the cancellation page's timeout example with the real timeout()
  combinator; bind executor_ref to a named executor.
- Document when_all/when_any all-fail semantics (when_any reports an unspecified
  failure); replace the FrameAllocator concept with the real allocator
  requirements and document frame_alloc_mixin.
- Document read into a DynamicBuffer, the ReadSource read overload, read_until,
  and write_now; the composed write takes its buffer sequence by value.
- Smaller buffer/stream/source corrections (byte-size note, empty/partial read).

Buffer and stream specification:
- Explain that const_buffer/mutable_buffer are non-owning handles: the caller
  owns the underlying bytes and their lifetime; the library manages only the
  handles and handle-sequences it produces.
- Strengthen the rationale for void* over std::byte/span, and state that
  treating a single buffer as a one-element sequence is a deliberate
  convenience applied consistently across the buffer API.
- Note on the ReadStream/WriteStream concepts that the single buffer archetype
  in the requires-clause is only a representative: the real contract is that
  the operation accepts any MutableBufferSequence / ConstBufferSequence, which
  a C++ concept cannot fully express.

Addresses cppalliance#273, cppalliance#287, and cppalliance#296.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants